Summary

Add an opt-in documentation skill that helps agents discover, assess, create, update, verify, and promote durable project documentation without treating .agents/work/ as the canonical project knowledge base.

The skill:

• discovers existing conventions such as docs/, doc/, root contribution/security files, generated references, and documentation-site configuration before choosing a location;
• offers docs/ initialization only when no canonical location exists and the user approves it;
• supports read-only scans across architecture, development, operations, security, runbooks, specifications, API, data, product, and contributing topics;
• lets users select which topics to document and creates directories only when adding useful documents;
• distinguishes repository evidence from unknown policy or intent, avoiding unsupported claims;
• promotes enduring work-item decisions into canonical project documentation while linking the two locations and avoiding competing sources of truth.

Why

Work items already preserve task-local decisions and research, but the project does not currently provide a workflow for turning selected, enduring outcomes into documentation that should guide future unrelated work. This skill adds that promotion path while preserving the existing boundary:

• .agents/work/ holds task state and work-local context;
• the host repository's established documentation system holds canonical project knowledge;
• AGENTS.md remains a concise map to deeper documentation.

The proposed topic tree is guidance rather than mandatory scaffolding. Existing repository conventions always win, and empty topic directories are never created.

Changes

• Add .agents/skills/documentation/SKILL.md.
• Register documentation as an upstream core skill, including Claude Code discovery.
• Add installation coverage and rebuild the test fixture.
• Document the skill in the project and installed AGENTS.md templates, skills reference, and changelog.

Verification

• git diff --check passes.
• ./scripts/test.sh passes Bash syntax checks and ShellCheck.
• BATS tests were not run locally because bats-core is not installed; CI should execute them.